Skip to main content

快速开始

本页把旧版「成为开发者并创建 Key」的流程整理为 V3 接口的完整接入路径。完成后，你将拥有应用凭证、AccessKey 和 OAuth 访问令牌，并可以调用第一个 V3 接口。

接入前准备​

  • 确认你所在组织的用户管理员可以登录高仙云平台。
  • 准备一个用于接收邀请和激活邮件的邮箱。
  • 确认需要调用的机器人已经绑定到对应账号，并准备好机器人序列号。
  • V3 接口只确保兼容 AIO 1.6 及以上软件版本。

第一步：成为开发者​

组织内邀请开发者​

  1. 用户管理员登录高仙云平台，进入导航栏的 IAM。
  2. 打开 用户管理，点击右上角 添加用户。
  3. 输入被邀请人的邮箱，系统角色选择 开发者，业务角色按实际需要选择。
  4. 提交邀请，确认页面显示邀请成功。

其他组织邀请开发者​

独立租户客户可以由管理员代管理其他客户组织：

  1. 在高仙云平台的 IAM 中打开 客户中心，输入并搜索需要代管理的客户名称。
  2. 在目标客户右侧进入该客户的用户管理页面。
  3. 点击右上角 + 用户，输入被邀请人的邮箱。
  4. 系统角色选择 开发者，业务角色按实际需要选择，然后提交邀请。

激活开发者账号​

被邀请的开发者打开邮箱，按照激活邮件完成账号激活，然后登录开放平台。如果还没有开发者账号，请先完成上面的邀请流程。

为已有账号增加开发者角色​

如果账号已经存在但没有开发者角色，用户管理员可以按以下步骤补充角色：

  1. 登录高仙云平台，进入 IAM > 用户管理，搜索目标账号。
  2. 点击账号右侧的编辑角色操作。
  3. 在左侧选择 开发者，将其移动到右侧的生效区域，然后点击 确定。

第二步：创建应用并保存应用密钥​

  1. 登录开发者中心，进入 应用管理。
  2. 点击 创建，填写应用表单并提交。
  3. 下载应用密钥文件，并妥善保存其中的 ClientID 和 ClientSecret。

应用密钥文件通常按 ClientID,ClientSecret 的顺序提供两个值。实际文件中的值属于敏感凭证，请按字段名称分别保存，不要把完整文件内容粘贴到公开文档或代码仓库中。

密钥安全

ClientSecret 只能保存在服务端或安全的密钥管理系统中。不要把应用密钥提交到代码仓库、前端页面、日志或工单中。

第三步：创建 AccessKey 并保存密钥​

  1. 进入 AccessKey 管理。
  2. 点击 创建，填写表单并提交。
  3. 下载 AccessKey 文件。文件通常按 AccessKeyID,AccessKeySecret 的顺序提供两个值，请分别保存 AccessKeyID 和 AccessKeySecret。OAuth 请求中的 open_access_key 使用文件里的 AccessKeySecret，不是 AccessKeyID。
只展示一次

AccessKeySecret 可能只在创建成功页面或下载文件中展示。请在离开页面前完成下载，并像保护密码一样保护它。

第四步：获取 OAuth 访问令牌​

打开左侧 认证服务 > 获取 OAuth 令牌，或直接使用下面的请求。认证接口沿用旧版地址；成功后返回 access_token、refresh_token 和 expires_in。

curl -X POST 'https://<developer-host>/gas/api/v1alpha1/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
  "grant_type": "urn:gaussian:params:oauth:grant-type:open-access-token",
  "client_id": "<ClientID>",
  "client_secret": "<ClientSecret>",
  "open_access_key": "<AccessKeySecret>"
}'

请求字段说明：

字段说明
grant_type固定值 urn:gaussian:params:oauth:grant-type:open-access-token。
client_id应用密钥文件中的 ClientID。
client_secret应用密钥文件中的 ClientSecret。
open_access_keyAccessKey 文件中的 AccessKeySecret（通信密钥）。

令牌默认有效期为 24 小时。请根据返回的 expires_in 管理过期时间；令牌即将过期时，使用 认证服务 > 刷新 OAuth 令牌，并提交 refresh_token，无需重新授权。

第五步：调用第一个 V3 接口​

除认证接口外，V3 接口都以 /openapi/v3/ 开头，使用 POST 和 JSON 请求体，并携带 Bearer 令牌。例如，查询机器人当前状态快照：

curl -X POST 'https://<developer-host>/openapi/v3/robots/status/get' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "robotSnList": ["<robot-serial-number>"]
}'

成功响应遵循统一结构 {code, msg, data}，其中 code = 0 表示成功。状态快照不是实时数据，在线机器人会返回任务、电量、地图和位置等字段；离线机器人可能没有这些运行字段。

第六步：按业务域继续集成​

完成第一次调用后，可以按以下顺序扩展：

  1. 在 基础信息 中确认机器人和状态。
  2. 在 地图数据 中取得地图、画布、充电桩和地图资源。
  3. 在 任务与排班 > 能力与资源查询 中查询任务工作模式说明、机器人任务能力和任务资源。
  4. 在 任务与排班 中创建组合任务、排班或临时任务。
  5. 在 指令操作 中执行开始导航，并用查询指令状态/记录接口跟踪异步指令。

每个接口页面都提供在线调试面板、字段示例、响应样例和可复制的 curl。浏览器请求如果受到跨域限制，请复制 curl 到服务端或终端执行。